Welcome to BAABE! (*)  This is a new system designed specifically for RISC OS
computers, rotating around the BASIC and MessageTrans modules.  The
interpreter occupies one BASIC file, and it loads another (the script) as a
library.  All the text is held in seven message files, which determine
everything from cut scenes to the order the components of the command come
in.  The basic idea is that every adventure should be fully translatable, so
that the same adventure can be played in any language you please.

The longest adventure supplied is !Pyramid, but that was converted from a
different adventure system and has a number of idiosyncrasies.  The best
example of how to write adventures in this system is the !Example application
(which, by the way, is rather silly).  The !Template application contains the
bare minimum to get a working adventure, and is supposed to be used as a
starting point for coding your own games.

Well, there was supposed to be a long and detailed adventure illustrating all
the techniques and with lots of puzzles, but we won't go into that...

The programmer's reference manual for the system is supplied in StrongHelp
format, as 'BAABE'.  For advice on how to actually play games, read on...

(*) Bloody Awkward Adventure Back-End.

Requirements and notes
----------------------

Firstly, a warning.  This system is not yet considered stable.  It installs
its own exit handler to close message files before quitting, but I'm still
getting the occasional crash.  Therefore, watch out.

New Boot is recommended, or else Acorn's utility Do somewhere in Run$Path or
Library.

StrongED 4.67 or later is recommended for playing.  This is due to a bug in
TaskWindow handling in earlier versions which causes one character in every
128 to go AWOL.  For best results, set the wrapwidth of the window to 80 and
turn on word wrap.

It will not work in GraphTask.  This is because it treats the end-of-line
character as 10 (LF, |J) and GraphTask expects 13 (CR, |M) as well.
(Besides, why would you want to?)

Please don't try to play games in Edit.  For your own sake, get a better
editor.

There are no operating system requirements that I know of.  A word of
warning, though: it contains assembly language, so don't try to run it on a
6502!

Introduction to text adventures
-------------------------------

In case you don't know what a text adventure is, here is a short explanation.
Text adventures are what computer games were before graphics were invented.
The defining example of the genre is the Colossal Cave Adventure
('Adventure', 'Zork', catchphrase: 'You are in a maze of twisty little
passages, all alike.').  Numerous ports of this exist; at the time of
writing, Gareth Lock is attempting to convert it to BASIC.

The basic premise is that instead of pictures, there are words, and instead
of movement, fighting and interaction, you type more words back at the
computer.  The bit which translates your drivel into something the computer
understands is known as the 'interpreter'.

A text adventure is a turn-based game.  This means that, should you be
confronted with a raging dragon who's going to fry your head off in one
second, if need be, you can leave the computer, go downstairs and have a cup
of tea and a good think about exactly what item it would be a good idea to
use against the dragon.  When you come back, the computer will still be
patiently waiting for your response.

Conventionally, as accurate movement is impossible to implement in such a
system, the player in a text adventure is, at any one time, defined merely to
be in any one of a number of set locations, usually termed 'rooms'.  From
these locations, it is possible to move to adjacent ones by specifying a
compass direction in which to move, and each room will give you a list of
valid exits.  Obviously most people benefit enormously from drawing a map of
locations and exits as they go.

There are also objects in the game which you can interact with using a
different set of commands.  Conventionally, these include: 'get' (move an
object from the current room into your inventory), 'drop' (perform the
reverse), and 'put' (move an object from any location to inside another
object).  Some adventures may also include additional commands, such as
'push', 'pull', 'kick', 'throw', etc.

And that's mostly it.  You walk around between rooms and do the right things
with the right objects.

____________________________________________________________________________
                   The gamer's guide to the interpreter:
============================================================================

(1) Terminology:

In this section, the word 'verb' refers to the command specifying what the
interpreter should do ('get', 'put', 'inventory', etc.)  'noun' refers to an
object which appears in the game ('bell', 'cat', 'cheez').  Some verbs take
two nouns - the second one is referred to as the 'object'.

(2) Basic syntax:

Somewhat late in the day, I made a conscious decision to change the
underlying ethic of the interpreter.  Previously, I had been trying to
enforce grammatical conventions, but I eventually realised that there was no
way I could cover everything and I was simply digging a hole for myself in
terms of translatability.

Therefore, in the latest sentence model, I adopted ease of use over sense.
All that is necessary to type is:

<verb> [<noun> [<object>]]

The list of verbs is defined below... as for nouns, you'll just have to use
what you find.  This is not guaranteed to be a complete list - most games
will implement their own additions.

(3) Single verbs:

north, northeast, east, southeast, south, southwest, west, northwest, up,
down (n, ne, e, se, s, sw, w, nw, u, d)	Bet you can't guess what these do.
quit	Undoubtedly the most important one, unless you manage to complete the
	adventure first time.  May be abbreviated to 'q'.
wait	Causes a turn to compulsorily go by without doing anything else.
	May be abbreviated to 'z'.
look	Prints the full description of the current room, regardless of
	'terse' mode (see below).  May be abbreviated to 'l'.
inventory	Prints a list of what you're currently carrying.  May be
		abbreviated to 'inv' and further to 'i'.
verbose	From now on, full room descriptions will be printed every time you
	enter a room.
terse	From now on, full room descriptions will only be printed if you
	enter a room you haven't been in before.
score	Print the number of turns taken, your current score and the number
	of hints you've used.
exits	Print just the exits leading off from the current room.
load	Load a previously saved game - will prompt for filename.
save	Save your progress so far - will prompt for filename.
hint	Give hints.  Yes, there are hints!
silent	Long room descriptions are disabled under *any* circumstances,
	including the use of 'look'.  To turn off, type 'verbose' or 'terse'.
	This command will also prevent the game setting the flags which tell
	it whether you've been in certain rooms or not.  I don't recommend
	you play in this mode, because sometimes the descriptions contain
	important information.  It was mainly implemented for my benefit
	while playtesting, so I didn't have to wait for the same
	descriptions to endlessly scroll past.

(4) One noun verbs:

examine	Print an object's description.  May be abbreviated to 'x'.
get	Move an object from the current room to your inventory.  Also 'take',
	'grab'.
drop	Move an object from your inventory to the current room.  Also
	'replace'.
	Note that there is no limit on your inventory, apart from BASIC's
	string limit of 255 characters.

Examples:

examine female
get joke
drop pants

(5) Two noun verbs:

put	Put an object inside another.  Also 'place'.
say	Say something to somebody. Don't use quotes, by the way.
ask	Ask somebody about something.
tell	Tell somebody about something.
show	Show something to somebody.
give	Give something to somebody.

Not all of these are guaranteed to actually have any function in any
adventure.

Examples:

put foot mouth
say hello policeman
give money charity

(6) Plural:

The word 'all' (or, alternatively, 'everything') is a special noun, which, if
used, means 'perform this action on all objects within the scope of this
verb' (e.g. the command 'drop all' won't attempt to drop objects already on
the floor).  Note it only scans the top level - so 'examine all' won't
examine objects contained within other objects.

Some verbs have the use of this disabled on certain parameters.  Principally,
you can't use it as the second noun (container) of a 'put' statement.

Examples:

put all rucksack
drop all
tell all joke

(7) Pronouns:

The words 'it' and 'them' are automatically substituted by the interpreter
for the immediately preceding value of that parameter.

Examples:

get joke
deconstruct it

put tissue handbag
put gobstoppers it
eat them

get all
drop them

(8) Words to ignore:

By now you must by wondering, "What was he thinking, this being easier than
enforcing grammatical conventions?"  Well, there's good news coming up.  You
can still use grammatical conventions if you want!  All that happens is that
the interpreter removes certain words as it finds them, stripping each
sentence down to the bare minimum.

Also, all characters are translated to lower-case (even accented ones, by the
way), so you can also choose to follow that grammatical convention if you
want.

When I mentioned ease of use over sense, what I actually meant was that as
these words are unconditionally ignored, some surprising sentences are
valid...

Example:

put ball bag
Put ball bag
Put the ball bag
Put the ball into the bag
WitH puT INTo FrOM BALL on At go BaG

...all mean the same thing!

(9) Multiple words:

By now you must be wondering, "Are we really restricted to single word nouns
and verbs? That's really primitive!"  More good news!  You're not!  As long
as a certain form of words you use is covered by the appropriate message
file, the program will automatically detect what you mean.

Well, actually, that's not quite true - what it does is check to see if a
word is valid, and if it isn't, it adds the next word onto it and tries
again, and so on - so, for example, if you wanted to refer to 'ball
lightning' and the message file defined 'ball' as an acceptable abbreviation,
the next word 'lightning' will get interpreted as the second parameter.  This
can lead to surprising results with two noun verbs, so watch out.

Example:

Put the tennis ball into the plastic bag

(10) Multiple sentences:

You probably aren't wondering how you can type multiple commands on the same
line, but I'm going to tell you anyway.  The words 'and' and 'then', if
encountered, signify the end of the current command and the start of a new
one.  A comma (',') also has this effect, but does not need to be surrounded
by spaces.

Note that using a comma *and* an 'and' will cause the interpreter to attempt
to execute a blank statement.

Examples:

Put the tennis ball into the plastic bag and take the bag
get scroll, read it
Get all, drop box then put cat in box
Drop everything and go west

(11) Noun clashes:

Inevitably, in a large adventure there will be more than one of everything.
A special mechanism is included for getting around this.  Certain words are
defined to refer to more than one noun.  If they are singular, and there is
more than one of them currently present, you will be asked which noun you
actually meant. If they are plural, the action will be performed on each one
in turn, like a subset of the 'all' command.

Example:

Get coins
Put the silver coin in the silver slot and put the gold coin in the gold slot
Pull levers

(12) Translatability:

The interpreter has its own provision for translation.  The sentence
structure is fully configurable, according to taste and language - so the
verb could come last if you pleased, although note both other parameters are
always optional.  Unfortunately, in implementing this the distinction between
verbs and nouns had to be sacrificed, so you can't have the same words
defined as both verbs and nouns.

Also, if a certain flag for a verb is set, the two parameters will be
switched.  This is to allow for local grammatical conventions without having
to rewrite the relevant parts of the script to swap references to the two
parameters (e.g. in the verb 'ask' the person being addressed comes first,
but in 'say' it comes second).

(13) The hints system:

If you type the command 'hint', a numbered list of hint topics will come up.
What is in this list depends on what you have done so far - topics will be
added and removed according to your achievements, where you have been and
what you have investigated.

The hint topics are divided into any number of actual hints, starting at
useless and ending at explicit instructions on what to do.  Every time you
ask for a particular hint topic, you get a bigger spoiler.

Although you won't be penalised for using hints, the game will remind you
at the end of how many you've used.

(14) Hints and tips:

Remember you're talking to a dumb computer.  It can't understand elaborate
sentences.  Wherever possible, try to express the action you wish to perform
in one or two words.

As a rule, if the game doesn't understand a particular synonym for an object,
any form of words used in any description is pretty much guaranteed to be
valid.  (e.g. if the game refers to a 'small china cup' and you call it a
'mug', which it doesn't understand, as a rule, forms of words like 'get small
china cup' should work.

If your score goes up, it means you have advanced the adventure in some way.
If your score goes down, it means you have made the adventure impossible to
complete.  I spent a lot of time and effort on the loading and saving
functions.  Use them.

The first parameter to the verbs 'say', 'ask' etc. does not need to be a
valid noun, so you could 'say foobar to cashier' without a 'foobar' actually
existing in the adventure.  But if something doesn't exist, only the first
word will be treated as valid, and the rest will be treated as the second
parameter, as there is no way of telling where the divide should be.

If you get *really* stuck, the text files and BASIC script are not compressed
or encrypted in any way...

____________________________________________________________________________

History of this archive
-----------------------

Release 1 (8th September 2009): First version.

(23rd September 2009): This application is now distributed according to the
terms of the GNU General Public License, version 3.  No code changes.

Credits and contact
-------------------

This adventure system was entirely conceived and written by Martin Bazley.
So there.

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
details.

You should have received a copy of the GNU General Public License along with
this program.  If not, see <http://www.gnu.org/licenses/>.

The name BAABE has been officially registered with RISC OS Open Ltd.

The idea is that an adventure can be written without having to look inside
the interpreter at all, but if something needs improving or you spot a bug
that needs fixing, please let me know about it so it can be improved or fixed
in the main distribution.

My email address is:

 mailto:martin@bazleyfamily.co.uk

New versions of this archive should be available from:

 http://www.starfighter.acornarcade.com/mysite/
